MACD 5/MACD 5.bin/workbench/time/tptcron/tptcron.doc

Text File | 1990-03-29 | 19KB | 486 lines

TPTCron - CRON utility for the Amiga

TPTCron is a utility which executes AmigaDos tasks at regularly scheduled
times. TPTCron is capable of executing periodic events - tasks which must be
executed at specific time intervals. It is also capable of executing one-
shot tasks, scheduled through the use of an external command called
CronEvent. These one-shot events can be scheduled "on-the-fly" once TPTCron
has been started up.

TPTCron and CronEvent were written by Mike Oliphant.

TelePro Technologies wishes to acknowledge the work of Steve R. Sampson for
his initial PD cron, Rick Schaeffer who ported it to the Amiga, and
Christian Balzer who swatted some bugs in Rick's code and created AmiCron2,
the program upon which TPTCron is based.

Documentation by:  James Hastings-Trew
              and  Mike Oliphant
based on Rick and Christian's AmiCron2 documentation.

TPTCron is freeware - you are free to copy and distribute this program under
the following conditions: the original archive and this documentation must
be remain intact and unaltered, except for the inclusion of additional
example CronTab files. This program must not be sold for profit or included
in any commercial product without the express written permission of TelePro
Technologies. TelePro Technologies will in no event be liable for any
direct, indirect, or consequential damages to any equipment or software or
data, arising from the use of this software; the entire risk as to its
quality, performance, or fitness for any particular purpose is assumed by
the end user.

©1990 TelePro Technologies. All rights reserved.

TelePro Technologies,
20-1524 Rayner Avenue,
Saskatoon, Saskatchewan,
Canada,          S7N 1Y1




TPTCRON
------------------------------------------------------------------------
When TPTCron is first run it optionally reads a table of permanent,
periodic events to run from a file called CronTab, which we suggest be
located in your S: directory. TPTCron maintains this list of events to
execute in RAM.

We suggest that TPTCron should run in it's own CLI window. This is
suggested for two reasons:

    (1) The AmigaDOS commands that TPTCron executes need a place to
        print output, display errors, etc.
    (2) If you run TPTCron from your main CLI window, you could prevent
        a cron event from being executed properly by typing into that
        window.

If you do not wish to run TPTCron in it's own CLI window, you can RUN it
from your main CLI, by re-directing it's output to NIL:. This will
make it impossible to hold up a cron event by typing commands into that
CLI, but it will also make it impossible to see any output from TPTCron
or the programs it runs.


The syntax of TPTCron is as follows:

  TPTCron [path:crontab]

If TPTCron is run with no pathname specified for a CronTab file, it will set
itself up in memory, available for programming by CronEvent, with no list of
permanent periodic events to execute.

To re-direct TPTCron's output to NIL:, in case you wish to run TPTCron from
your main CLI, the syntax is as follows:

  TPTCron >NIL: [path:crontab]

To run TPTCron with the ability to execute periodic events, you must first
use your favorite editor to create a "CronTab" file. The format of CronTab
is very simple - it contains entries in the form of lines where each line
has 6 fields and each field is separated by "white space" (either tabs or
spaces) from it's neighbor. The fields are as follows:

Field | Name       | Range of legal values
------+------------+-----------------------------------------------
1     | Minute     | 0 - 59
2     | Hour       | 0 - 23  (0 = 12:00 a.m.  /  23 = 11:00 p.m.)
3     | Date       | 1 - 31
4     | Month      | 1 - 12  (1 = January  /  12 = December)
5     | Day        | 0 - 6   (0 = Sunday  /   6 = Saturday)
6     | Command    | This is the command to be run at the appointed
      |            | time. It will be run just as if typed into
      |            | the CLI.

Each entry for each of the first five fields should be a number in the legal
range for that field. If you substitute an asterisk (*) for a number in a
field it is taken to mean ALL possible numbers for that field. You may also
specify a SET of values for each field, by separating them with commas.
Similarly, you can specify a RANGE of values by separating them with a
hyphen (-). For example:

  ------------------------------------------------------------------

  Print the date in the TPTCron CLI window every minute:

* * * * * DATE

  Since there are asterisks in each field, TPTCron takes
  that to mean that at each legal interval, run the command DATE.
  Since the smallest interval is a minute, the DATE command will
  be executed every minute, regardless of the hour, date,
  month, or day.

  ------------------------------------------------------------------

  Print the date in the TPTCron CLI window on the hour, every hour:

0 * * * * DATE

  Since we have put a 0 in the minutes field, the command will now
  only execute whenever the minutes equals 0 - once each hour.

  ------------------------------------------------------------------

  Run UUPC at 4:30 a.m. every day except Saturday and Sunday:

30 4 * * 1-5 UUPC -siscuva

  Here we are asking to run an event when minutes equals 30,
  hours equals 4 (which will be at 4:30 a.m.), any date,
  any month, and only in the RANGE of days 1 to 5 (Monday to Friday).
  Notice that we are running a command with command line parameters.
  There is no need to quote commands that contain spaces - everything
  after the fifth numeric field is taken to be one entire command string
  to be executed.

  ------------------------------------------------------------------

  Incrementally backup the files every other day at 7:30 p.m.:

30 19 * * 1,3,5 sdbackup -l -s LAST dh0: incbkup_1:

  Here we are asking for an event at 1930 (7:30 p.m.), any date
  day, any month, but only on the SET of days 1, 3, and 5 (Monday,
  Wednesday, and Friday).

  ------------------------------------------------------------------

  Backup the files on the 1st and 15th of each month at 1:00 am

00 1 1,15 * * sdbackup -l dh0: SemiBkup_1:

  Here we are asking for an event at 1:00 a.m., on the SET of dates
  1 and 15, any month, any day.

  ------------------------------------------------------------------

CronTab entries *MUST* be left justified starting in column 1 and each entry
must contain 6 fields, each separated by spaces or tabs. There can be as
many entries in the CronTab table as you like.

You may also put comments into your CronTab file, with the use of the "#"
character. If the first column contains a "#", the line is considered to be
a comment, and the rest of the line will be ignored by TPTCron.

The events that TPTCron schedules from the CronTab file are called PERMANENT
events. If you wish to manipulate the permanent events once TPTCron is
running, you must re-edit your CronTab file, or have a secondary CronTab
file available, and use the CronEvent program (see below) to read the new
CronTab file into TPTCron.




CRONEVENT
------------------------------------------------------------------------
Once TPTCron is running, you can create a list of ONE-SHOT events with a
second program called CronEvent. The events which can be scheduled with
CronEvent will only be executed once, after a given time interval. CronEvent
can be used to list the pending one-shot events, add to the list, delete
events from the list, or stop the TPTCron program. The format for the
CronEvent command is as follows:

CronEvent (add|delete|list|read|tablist|when|quit) [minutes] [command]

The commands can be shortened to just the first letter of each command name.
Here is an explanation of each command:

Add (a)
-------
When given the add command, CronEvent expects two more parameters to be
given - the number of minutes to wait until executing the event, and the
command to be executed. If the command to be executed has spaces or requires
further command line parameters, it must be quoted.
After the given number of minutes has expired, the command will be executed
on the next minute mark. There is one special case for the number of minutes
given to the add command - when the minutes parameter is zero, the event will
occur immediately.

Syntax:
    CronEvent a (minutes) (command)


Delete (d)
----------
When given the "delete" command, CronEvent expects one more parameter to be
given - the name of the command to delete from the list. ALL occurrences of
that particular command will be deleted from the list. For instance, if
there were more than one DATE command in the list, then:
    CronEvent d DATE
would delete all pending DATE commands. You may use ARP style wildcards with
the delete command. For instance:
    CronEvent d D*
would delete all pending events that start with the letter D,:
    CronEvent d ~SI
would delete all pending events except for SI.
Please note: CronEvent will not delete pending PERMANENT events set up
through the CronTab file.

Syntax:
    CronEvent d (command)


List (l)
--------
When given the "list" command, CronEvent requires no other parameters. The
complete list of pending one-shot events will be printed in the TPTCron CLI
window. Please note: the list command will not list pending PERMANENT events
set up through the CronTab file. If you wish to view the list of permanent
events, you should use the tablist command, explained below.


Syntax:
    CronEvent l


Read (r)
--------
When given the "read" command, CronEvent optionally requires one more
parameter - the name of a new CronTab file. The new CronTab file will
replace the original table of pending PERMANENT events. If you give no
pathname for a new CronTab file, CronEvent will attempt to read in the LAST
CronTab file that you used. Failing that, it will look for the default
pathname of S:CronTab, and load that file. If you wish to remove all
pending permanent events, but do not wish to terminate TPTCron, then you
will have to create a CronTab file that has no entries, and use the read
command to load that into TPTCron.


Syntax:
    CronEvent r [path:crontab]


Tablist (t)
-----------
When given the tablist command, CronEvent requires no other parameters. The
complete list of pending PERMANENT events will be printed in the TPTCron CLI
window. Please note: tablist will not list any pending one-shot events. If
you wish to view the list of one-shot events, you should use the list
command, explained above.


Syntax:
    CronEvent t


When (w)
--------
When given the "when" command, CronEvent requires one more parameter to be
given - the name of the command to list. For instance, if there was a
DATE command in the list, then:
    CronEvent w DATE
would print when the pending DATE command would be executed in your
current CLI. If there is more than one of that type of command in the list,
the "when" command will only list the first one. Please note: CronEvent
will not list pending PERMANENT events set up through the CronTab file.

Syntax:
    CronEvent w (command)

Note: both LIST and WHEN will list event times as the exact minute mark
at which they will occur. For instance, if we enter the command:
    CronEvent a 5 si
at the time 05:03:23, and then enter this command:
    CronEvent l
we will see the following report:

    TPTCron: List of pending events:
    ================================
    Time: Tue Mar  6 05:08 - Command: <si>

The original seconds are ignored, and the time is rounded backwards to the
even minute mark.


Quit (q)
--------
When given the "quit" command, CronEvent requires no other parameters. The
TPTCron program will be immediately shut down, and all pending events will
be cancelled. Alternatively, if you run TPTCron in its own CLI, then typing
a CRTL-C in that CLI will also shut down the TPTCron program. This method
will cause TPTCron to abort on the next minute mark. If you wish, you can
also alternatively do a status command to find out what task number TPTCron
has, and issue a "break <tasknumber>" command at the CLI to terminate its
operation.

Syntax:
    CronEvent q



SETUP
---------------------------------------------------------------------

CronEvent requires that the file "ARP.library" be located in your LIBS:
directory. We have included the proper version of the ARP.library in the
archive that the files came in.

To facilitate the correct operation of TPTCron, we have included three
script files which should be copied to your S: directory. These are:
    CronStart
    TPTScript
    CronTab
CronStart is a batch file which will create a small CLI window, and execute
a second script, TPTScript which will start up TPTCron in that new window.
CronTab is a sample CronTab file which will print the date in that CLI every
minute.

You should set the script bit for the CronStart file, especially if
you are running WorkBench 1.3, and include a PATH to your S: directory.

In case your copy of the archive does not contain those script files, they
are listed here:

CronStart:
=========
run newcli RAW:0/11/400/100/TPTCron S:TPTScript


TPTScript:
=========
TPTCron S:CronTab
endcli


CronTab:
=======
* * * * * date


We have also included a small batch file called Execute.ME which will copy
all of the files used by TPTCron to the proper directories on your system.

Execute.ME:
===========
copy TPTCron C:
copy CronEvent C:
copy CronStart S:
protect S:CronStart +s  ;this assumes that you have Workbench 1.3 - remove
                        ;this line if this is not the case.
copy TPTScript S:
copy CronTab S:
copy ARP.library LIBS:  ;remove this line if your version of the ARP.library
                        ;is more recent than 39.1



Programmer's Information
---------------------------------------------------------------------
The CronEvent program communicates with the TPTCron program via a message
port. It is therefore very easy to have other programs access TPTCron
directly.  The following files have been included in this distribution to
facilitate this process:


_CronEvent.o:   A Manx 3.6a format object file.
Cron.h:     An include file containing relevant #defines.
CronTest.c: A sample program that communicates with TPTCron directly.


_CronEvent.o contains a single routine, CronEvent(), that operates as
follows:

(long) CronEvent((unsigned char)commandtype, (long)minutes, (char *)command)

Where 'commandtype' is one of the following values:

    #define ADDEVENT    1   /* Add an event */
    #define DELEVENT    2   /* Delete an event */
    #define LISTEVENTS  3   /* List the dynamic events */
    #define CRONEXIT    4   /* Shut down TPTCron */
    #define WHENEVENT   5   /* Check the time for an event */
    #define READFILE    6   /* Read a CronTab file */
    #define TABLIST     7   /* List the CronTab events */

'minutes' is the number of minutes before you want the event to occur
and 'command' is a string containing the command to be executed.

CronEvent returns the following result codes:

    #define CNOERR       0L /* Command was successful */
    #define OUTOFMEM    -1L /* Error allocating memory */
    #define BADSYNTAX   -2L /* Invalid command type */
    #define NOCRON      -3L /* TPTCron is not active */
    #define TABNOTFOUND -4L /* CronTab file not found */
    #define NOEVENTS    -5L /* There are no events present */

The command types DELEVENT and WHENEVENT return special result codes.
A DELEVENT command returns the number of events that were deleted.
A WHENEVENT command returns a time-encoded long that is suitable for calling
ctime() with, or a NULL if the event was not found.

Cron.h contains the #define statements mentioned above.  It also declares
CronEvent() as returning a long.

CronTest.c is a simple program that uses _CronEvent.o and Cron.h to interact
with TPTCron.



TELEPRO TECHNOLOGIES
-----------------------------------------------------------------------
TelePro Technologies is a company devoted to producing the finest possible
telecommunication and electronic mail software for the Commdore Amiga.

TelePro Technologies is currently developing DIALOG, a bulletin board
system for the Commodore Amiga. When completed, DIALOG will be the finest,
most complete program of its type. Features of DIALOG include:

> very low memory usage. Under typical load, DIALOG will consume around 30K
  to 50K of memory. If you configure DIALOG to have no screen, then there
  is 0K of chip RAM utilized.

> Adherence to FidoNet message standards makes interfacing the program to
  existing packers and mailers a breeze. FidoNet standard message threading
  is also completely supported.

> The software is UUCP-friendly in that it will transfer UUCP calls over
  to the appropriate software.  This allows a 24hr BBS to be run concurrently
  with UUCP traffic.  The ability to read and write UUCP mail and participate
  in UseNet newsgroups is in the works.

> File transfers with all of the most popular file transfer protocols. We
  currently support Xmodem, Xmodem 1K, and Ymodem. We also support XPR
  library protocols - our BBS will never lack the latest in file transfer
  technology. The BBS currently supports the Zmodem XPR library.

> Unlimited number of message areas. Unlimited number of messages in each
  area. Unlimited file areas. You can set up a board as large or as small as
  you desire.

> Multi-Line/Multi-User support. Features include on-line conferencing -
  users are able to establish conference "rooms" on-line, and engage in
  multi-participant conversations. Planned features include multi-player
  on-line gaming.

> Extra fast operation, and familiar, easy to use interface. Planned is
  a full intuition user-interface for Sysop maintenance. On-line control
  of all BBS operations is now implemented for sysop and co-sysop
  maintenance.

> Infinite user-levels. You can exactly the configure the access of each
  user to each area of your BBS, or set areas for maintenance free auto-
  access. In addition, each user can select which areas of your board that
  they want to see. Totally Sysop and user friendly.

> Infinitely expandable with external programs and games that use standard
  CLI interfaces.

We are currently running a development system at [phone]. It runs 24
Hours a day, 300/1200/2400/9600/14400 baud HST. There is no validation
period required - you will have full access on your first call. If you are
interested in our product, give it a call and try it out.


TPTCron was developed to work in conjunction with DIALOG, and is
used for scheduling daily FidoNet events, user time limits, and other
miscellaneous timing tasks required in the operation of a BBS.



If you wish to contact the author of TPTCron via UUCP, Mike Oliphant can
be reached at:

dvinci!telepro!oliphant